home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 076-100 / 087 / commodities / functions (.txt) < prev    next >
Microsoft Windows Help File Content  |  1995-03-13  |  31KB  |  820 lines
  1. :bk=0
  2.     Commodities Exchange Function Reference
  3.         v0.3 March 19, 1987
  4.         Jim Mackraz, San Jose, California
  5. NOTE: Starting with Version 0.3, new functions are added to the
  6. end of this file (and appended to the file "funcsummary").
  7. NAME    CreateCxObj()
  8.     CxObj    *co = CreateCxObj(type, arg1, arg2);
  9.     LONG    type;
  10.     LONG    arg1;
  11.     LONG    arg2;
  12. DESCRIPTION
  13.     Creates a Commodities Object of type 'type.'  It is not proper
  14.     to call this function directly.  Each object creation routine
  15.     except CxBroker() is defined as a macro in "cxusr.h."  The
  16.     routines are independently documented.
  17.     Note that the handle returned is a pointer to an abstract type
  18.     named 'CxObj.'  This type is defined as a LONG in "cxusr.h" but
  19.     internally has more content.  The specific size and contents of
  20.     internal data structures are 'private.'
  21.     All functions which operate on a Commodities object are made with
  22.     a reference to the thirty-two bit value returned by this function
  23.     (or CxBroker()).
  24. DIAGNOSTICS
  25.     A NULL returned value indicates that the requested object could not
  26.     be created, typically for lack of system memory.  Minor problems in
  27.     creating an object, such as providing a bad filter description to
  28.     CxFilter(), typically don't cause failure, but are recorded in
  29.     an internal error field in the new object.
  30. SEE ALSO
  31.     CxObjError(), CxFilter(), CxTypeFilter(), CxSender(), CxSignal(),
  32.     CxTranslate(), CxDebug(), CxCustom(), CxBroker()
  33. NAME    CxBroker()
  34.     CxObj    *broker    =    CxBroker(nb, error);
  35.     struct NewBroker    *nb;
  36.     LONG                *error;
  37. DESCRIPTION
  38.     Creates a broker from the specification found in the NewBroker
  39.     structure pointed to by 'nb.'  
  40.     The purposes and meaning of the fields are described below.
  41.     See also the include file "broker.h."
  42.     struct NewBroker {
  43.         BYTE    nb_Version;
  44.         BYTE    *nb_Name;
  45.         BYTE    *nb_Title;
  46.         BYTE    *nb_Descr;
  47.         SHORT    nb_Unique;
  48.         BYTE    nb_Pri;
  49.     'nb_Version' is the way that future versions of the Commodities
  50.     library can identify which version of the NewBroker structure
  51.     you are using.  This should be set to NB_VERSION, defined in
  52.     "broker.h."
  53.     'nb_Name' is a string which is to be the name of the broker
  54.     Node which is created.  This name is application internal,
  55.     and is used only to find the broker Node in the Commodities
  56.     Object List.
  57.     'nb_Title' and 'nb_Descr' are two strings which appear to the
  58.     user and describe the application the broker is representing.
  59.     Note that all strings above are copied into the broker object.
  60.     The maximum length of these strings that will be recognized are
  61.     defined by constants in "broker.h."
  62.     'nb_Unique' is a field that indicates what should happen if
  63.     a broker of the same name (nb_Name) already exists in the
  64.     Commodities Object List.  Constants in "broker.h" allow
  65.     the caller to specify whether another broker is to be created,
  66.     and whether any existing broker of the same name should be
  67.     notified that an attempt at creating a duplicate has been made.
  68.     'nb_Pri' specifies with what priority in the Commodities
  69.     Object List that the new broker is to be inserted.  Higher
  70.     priority nodes appear earlier in a list.  See "broker.h"
  71.     for guidelines for priorities of different types of
  72.     applications.  It is strongly recommended that the
  73.     ToolTypes environment of an application be used to allow the
  74.     end-user to set the priority of the broker.
  75. DIAGNOSTICS
  76.     Returns NULL in the event of failure.  If the pointer 'error'
  77.     is non-null, a further diagnostic code will be placed at
  78.     that address.  Error codes are in "broker.h" and include:
  79.     CBERR_OK
  80.         No problems; broker created OK.
  81.     CBERR_SYSERR
  82.         System problems, not your fault.  Sign of low memory or
  83.         big problems.
  84.     CBERR_DUP
  85.         The nb_Unique field specified that only one broker of
  86.         'nb_Name' should be allowed, and one already exists.
  87.     CBERR_VERSION
  88.         The field 'nb_Version' is unknown to the running version
  89.         of "commodities.library."
  90. SEE ALSO
  91.     FindBroker()
  92.     Brokers and Application Sub-Trees (in Reference Manual)
  93. NAME    CxFilter()    --    MACRO
  94.     CxObj *filter = CxFilter(description);
  95.     BYTE    *description;
  96. DESCRIPTION
  97.     Creates an input event filter object which matches Commodities
  98.     Input Messages fitting the 'description' string.  If
  99.     'description' is NULL, the filter will not match any messages.
  100.     A filter may be modified by the functions SetFilter(), using
  101.     a description string, and SetFilterIX(), which takes a 
  102.     binary Input Expression as a parameter.
  103.     This function is a C-language macro for CreateCxObj(), defined
  104.     in "cxfunctions.h."
  105. DIAGNOSTICS
  106.     Returns NULL if the function fails, which only occurs
  107.     if there is no memory for the new filter object.  If there
  108.     is a problem in the description string, the internal error
  109.     code of the filter object will be set to so indicate.  This
  110.     error code may be interrogated using the function CxObjError().
  111. SEE ALSO
  112.     CreateCxObj()
  113.     SetFilter(), SetFilterIX(), CxObjError()
  114.     Objects and Message (in Reference Manual)
  115.     Input Expressions and Description Strings
  116.     Objects and Messages (in Reference Manual)
  117.     Error Handling    (in Reference Manual)
  118. NAME    CxTypeFilter()    --    MACRO
  119.     CxObj *typef = CxTypeFilter(typemask);
  120.     LONG    typemask;
  121. DESCRIPTION
  122.     Creates a Commodities Object similar to CxFilter(), but one
  123.     that diverts all Commodities messages whose type, which is
  124.     always a power of two, matches a bit set in 'typemask.'
  125.     Values of message types are given in "cxusr.h."
  126.     This function is a C-language macro for CreateCxObj(), defined
  127.     in "cxfunctions.h."
  128. DIAGNOSTICS
  129.     Returns NULL if the function fails, which only occurs
  130.     if there is no memory for the new filter object.  If there
  131.     is a problem in the description string, the internal error
  132.     code of the filter object will be set to so indicate.  This
  133.     error code may be interrogated using the function CxObjError().
  134. SEE ALSO
  135.     CreateCxObj()
  136.     SetFilter(), SetFilterIX(), CxObjError()
  137.     Object and Messages (in Reference Manual)
  138.     Input Expressions and Description Strings
  139.     Error Handling
  140. NAME    CxSignal()    --    MACRO
  141.     CxObj    *signaler = CxSignal(task, signal);
  142.     struct Task    *task;
  143.     LONG        signal;
  144. DESCRIPTION
  145.     This function creates a Commodities signal object.  The action
  146.     of this object on receiving a Commodities message is to
  147.     send the 'signal' to the 'task.'  The caller is responsible
  148.     for allocating the signal and determining the proper task ID.
  149.     Note that 'signal' is the signal value as returned by
  150.     AllocSignal() (example: 3) , not the mask made from
  151.     that value (i.e., not binary 0000000000001000).
  152.     This function is a C-language macro for CreateCxObj(), defined
  153.     in "cxfunctions.h."
  154. DIAGNOSTICS
  155.     Returns NULL if the object could not be created.
  156. SEE ALSO
  157.     CreateCxObj()
  158.     Objects and Messages (in Reference Manual)
  159.     exec.library/Signal(), exec.library/AllocSignal(),
  160.     exec.library/FindTask()
  161. NAME    CxSender()    --    MACRO
  162.     CxObj    *sender = CxSender(port, id)
  163.     struct MsgPort    *port;
  164.     LONG            id;
  165. DESCRIPTION
  166.     This function creates a Commodities sender object.  The action
  167.     of this object on receiving a Commodities message is to
  168.     copy the Commodities message into a standard Exec Message,
  169.     to put the value 'id' in the message as well, and to send the
  170.     message off to the Message Port 'port.'
  171.     The value 'id' is used so that an application can monitor
  172.     messages from several senders at a single port.  It can
  173.     be retrieved from the Exec message by using the function
  174.     CxMsgID(). The value can be a simple integer ID, or a pointer
  175.     to some application data structure, for example.
  176.     Note that Exec messages sent by sender objects arrive
  177.     asynchronously at the destination port.  Do not assume 
  178.     anything about the status of the Commodities message which
  179.     was copied into the Exec message you received.
  180.     All Exec messages sent to your ports must be replied.
  181.     Messages may be replied after the sender object has been
  182.     deleted.
  183.     This function is a C-language macro for CreateCxObj(), defined
  184.     in "cxfunctions.h."
  185. DIAGNOSTICS
  186.     Returns NULL if the sender object cannot be created.
  187. SEE ALSO
  188.     CreateCxObj()
  189.     exec.library/PutMsg(), exec.library/ReplyMsg()
  190.     CxMsgID()
  191. NAME    CxTranslate()    --    MACRO
  192.     CxObj    *translator = CxTranslate(ie);
  193.     struct InputEvent    *ie;
  194. DESCRIPTION
  195.     This function creates a Commodities 'translate' object. 
  196.     The action of this object on receiving a Commodities
  197.     message is to replace that message in the commodities network
  198.     with a chain of Commodities input messages.
  199.     One new Commodities input message for each input event
  200.     in the linked list starting at 'ie' (and NULL terminated).
  201.     The routing information of the new input messages will be
  202.     copied from the input message they replace.
  203.     The linked list of input events associated with a translate
  204.     object can be changed using the SetTranslate() function.
  205.     If 'ie' is NULL, the null translation occurs: that is, the
  206.     original commodities input message is disposed, and no
  207.     others are created to take its place.
  208.     This function is a C-language macro for CreateCxObj(), defined
  209.     in "cxfunctions.h."
  210. DIAGNOSTICS
  211.     Returns NULL if the translate object cannot be created.
  212. SEE ALSO
  213.     CreateCxObj()
  214.     SetTranslate()
  215.     Commodities Input Messages and Filters
  216. NAME    CxCustom()    --    MACRO
  217.     CxObj    *custom = CxCustom(action, id);
  218.     LONG    (*action)();
  219.     LONG    id;
  220. DESCRIPTION
  221.     This function creates a custom Commodities object.  The action
  222.     of this object on receiving a Commodities message is to
  223.     call a function of the application programmer's choice.
  224.     The function provided ('action') will be passed a pointer to
  225.     the actual commodities message (in commodities private data
  226.     space), and will actually execute as part of the input handler
  227.     system task.  Among other things, the value of 'id' can be
  228.     recovered the message by using the function CxMsgID().
  229.     The purpose of this function is two-fold.  First, it allows
  230.     programmers to create Commodities Exchange objects with
  231.     functionality that was not imagined or chosen for inclusion
  232.     by the designers.  Secondly, this is the only way to act
  233.     synchronously with Commodities. 
  234.     For further explanation and examples, consult the Reference
  235.     Manual.
  236.     This function is a C-language macro for CreateCxObj(), defined
  237.     in "cxfunctions.h."
  238. DIAGNOSTICS
  239.     Returns NULL if the custom object cannot be created.
  240. SEE ALSO
  241.     CreateCxObj()
  242.     Custom Objects (in Reference Manual)
  243.     CxMsgID()
  244. NAME    CxDebug()    --    MACRO
  245.     CxObj    *debugger = CxDebug(id);
  246.     LONG    id;
  247. DESCRIPTION
  248.     This function creates a Commodities debug object.  The action
  249.     of this object on receiving a Commodities message is to
  250.     print out information about the Commodities message through
  251.     the Serial port (using the kprintf() routine).  The value
  252.     'id' will also be displayed.
  253.     Note that this is a synchronous occurence (the printing
  254.     is done by the input device task).  If screen or file
  255.     output is desired, using a sender object instead of
  256.     debug object is necessary, since such output is best
  257.     done by your application process.
  258.     This function is a C-language macro for CreateCxObj(), defined
  259.     in "cxfunctions.h."
  260. DIAGNOSTICS
  261.     Returns NULL if the debug object cannot be created.
  262. SEE ALSO
  263.     CreateCxObj()
  264.     CxSender()
  265.     exec_support/kprintf()
  266. NAME    DeleteCxObj()
  267.     void    DeleteCxObj(co);
  268.     CxObj    *co;
  269. DESCRIPTION
  270.     Deletes a Commodities object of any type.  If the object
  271.     is linked into a list, will first be removed.  Note that
  272.     the handle 'co' is invalid after this function is called.
  273.     Note also that deleting an object which has other objects attached
  274.     to it may be undesirable.  Use the function DeleteCxObjAll()
  275.     to delete an entire sub-tree of objects.
  276. DIAGNOSTICS
  277.     None.  Possible system crash if fed fiction.
  278. SEE ALSO
  279.     exec.library/Remove()
  280.     DeleteCxObjAll()
  281. NAME    DeleteCxObjAll()
  282.     void    DeleteCxObjAll(co);
  283.     CxObj    *co;
  284. DESCRIPTION
  285.     This function deletes the Commodities object 'co,' and also
  286.     recursively deletes all objects attached to 'co,' and the
  287.     objects attached to them.
  288.     If 'co' is linked into a list, it is removed first.  Note
  289.     that the handle 'co' is invalid after this function is called.
  290.     This function is useful when an application exits: most
  291.     applications can clean up completely by deleting the
  292.     entire sub-tree of objects starting at their broker.
  293. DIAGNOSTICS
  294.     None.  Definite system crash if fed fiction.
  295. SEE ALSO
  296.     exec.library/Remove()
  297.     DeleteCxObj()
  298. NAME    CxObjType()
  299.     LONG    type = CxObjType(co);
  300.     CxObj    *co;
  301. DESCRIPTION
  302.     This function should not really be necessary.  It returns
  303.     the type of a Commodities object, which you should already
  304.     know, since you created it in the first place.
  305.     Values for 'type' are given in "cxusr.h."
  306. DIAGNOSTICS
  307.     The value of 'type' will be CX_INVALID if you pass in a value of
  308.     NULL for 'co.'  If you pass a random value for 'co,' you
  309.     will get a random answer.
  310. SEE ALSO
  311.     All Commodities object creation routines.
  312. NAME    ActivateCxObj()
  313.     LONG    previous = ActivateCxObj(co, true);
  314.     CxObj        *co;
  315.     LONG        true;    /* Aztec user's take note    */
  316. DESCRIPTION
  317.     Commodities objects of all types maintain an "activation state."
  318.     If an object is "active," then it performs its particular action
  319.     whenever a Commodities message arrives.  If the object is
  320.     "inactive," no action is taken, and the message goes on to its
  321.     next destination.
  322.     All objects are created in the "active" state except brokers,
  323.     which are created "inactive."  Thus, after you create your
  324.     broker and hang a tree of objects off of it, you must remember
  325.     to use this function to activate your broker.  This causes it
  326.     it to divert all messages to your tree of objects.
  327.     This function activates 'co' if 'true,' and deactivates it
  328.     otherwise.  The previous value of activation is returned:
  329.     zero for inactive, non-zero for active.
  330. DIAGNOSTICS
  331.     None.
  332. SEE ALSO
  333.     CxBroker()
  334.     Brokers and Application Sub-Trees (in Reference Manual)
  335. NAME    SetTranslate()
  336.     LONG    error = SetTranslate(translator, ie);
  337.     CxObj                *translator;
  338.     struct InputEvent    *ie;
  339. DESCRIPTION
  340.     This function replaces the translation list of a Commodities
  341.     translate object 'translator' with the linked list starting at 'ie.'
  342.     A null value for 'ie' indicates that the object 'translator'
  343.     should swallow all Commodities messages that are sent its way.
  344.     Note that the input events are not copied into Commodities private
  345.     memory, but the value of ie is used--asynchronously to the
  346.     application program--to find a chain of InputEvents in the
  347.     application's data space.
  348.     At the time of translation, though, each input event is copied
  349.     into its own new Commodities message.
  350.     This means that no other Commodities user, nor Commodities itself
  351.     will be modifying your list of InputEvents.  On the other
  352.     hand, your program must not corrupt the input event chain
  353.     that has been presented to a translator. 
  354. DIAGNOSTICS
  355.     Returns zero if there is no problem, otherwise an error code
  356.     with values found in "cxusr.h."  The only forseeable error
  357.     could occur if 'translator' was not in fact a translate object.
  358. SEE ALSO
  359.     include:devices/inputevent.h
  360.     CxTranslate()
  361. NAME    SetFilter()
  362.     void    SetFilter(filter, text);
  363.     CxObj    *filter;
  364.     char    *text;
  365. DESCRIPTION
  366.     Changes the matching condition of a Commodities input filter to
  367.     that described by the input description string 'text.'
  368. DIAGNOSTICS
  369.     The internal error of 'filter' will have the COERR_BADFILTER
  370.     bit set or cleared depending on the failure or success (resp.)
  371.     of SetFilter().
  372. SEE ALSO
  373.     SetFilter(), SetFilterIX(), CxObjError()
  374.     Commodities Input Messages and Filters
  375.     Input Expressions and Description Strings
  376. NAME    SetFilterIX()
  377.     LONG    error = SetFilterIX(filter, ix);
  378.     CxObj    *filter;
  379.     IX        *ix;
  380. DESCRIPTION
  381.     Changes the matching condition of a Commodities input filter to
  382.     that described by the binary input expression pointed by 'ix.'
  383.     Input expressions are defined in the file "ix.h."  It is important
  384.     to remember that the first field of the input expression structure
  385.     must indicate which type of version of the input expression structure
  386.     is being used.  See "ix.h."
  387. DIAGNOSTICS
  388.     If 'error' returned is non-zero, it contains an error code from
  389.     "cxusr.h."
  390. SEE ALSO
  391.     SetFilter(), SetFilterIX(), CxObjError()
  392.     Commodities Input Messages and Filters
  393.     Input Expressions and Description Strings
  394. NAME    ParseIX()
  395.     LONG    failurecode = ParseIX(string, ix);
  396.     char    *string;
  397.     IX        *ix;
  398. DESCRIPTION
  399.     Given an input description string and an allocated, valid input
  400.     expression, sets the fields of the input expression to 
  401.     correspond to the description string.
  402. DIAGNOSTICS
  403.     CHANGED FOR v0.3!!!
  404.     Returns zero if the string WAS successfully parsed.
  405.     Error codes will be formalized later.
  406. SEE ALSO
  407.     Input Expressions and Description Strings
  408. NAME    CxObjError()
  409.     LONG    error = CxObjError(co);
  410.     CxObj    *co;
  411. DESCRIPTION
  412.     When a function acting on an object fails, it records the failure
  413.     in the object's internal data.  This function returns the
  414.     accumulated error value.  The values are represented by flag
  415.     bits defined in "cxusr.h."  Several errors may be recorded
  416.     by multiple bits in 'error.'
  417.     The possible errors (at current writing) are:
  418.     COERR_ISNULL
  419.         The value of parameter 'co' was in fact NULL.  This error
  420.         means "the problem with the object you inquire about is
  421.         that it failed to be created."
  422.     COERR_NULLATTACH
  423.         Using the Commodities list manipulation functions, an
  424.         attempt was made to add a NULL object to the list belonging
  425.         to 'co.'  This allows a line of code as follows to exist
  426.         in an error-tolerant program:
  427.             AttachCxObj(filter, CxSender(myport, MY_ID));
  428.     COERR_BADFILTER
  429.         The most recent filter specification for a Filter object
  430.         was faulty.  This happens if no sense can be made out
  431.         of a description string, or if an Input Expression (IX)
  432.         has in invalid format or version byte.  (See "ix.h.")
  433.         When this bit is set in a filter's error field, the
  434.         filter will match nothing, but this is not the proper
  435.         way to "turn off" a filter.  Use ActivateCxObj().
  436.     COERR_BADTYPE
  437.         A type specific operation, such as SetFilterIX(), was called
  438.         for object 'co,' but 'co' isn't of the proper type.
  439. DIAGNOSTICS
  440.     Nothing but.
  441. SEE ALSO
  442.     SetFilter(), SetFilterIX(), AttachCxObj(), ActivateCxObj(),
  443.     ClearCxObjError()
  444. NAME    ClearCxObjError()
  445.     void    ClearCxObjError(co);
  446.     CxObj    *co;
  447. DESCRIPTION
  448.     Clears the accumulated error value of Commodities object 'co.'
  449.     It is unwise to do this to a filter if COERR_BADFILTER is set.
  450.     This will fool the Commodities Exchange into thinking the
  451.     filter is OK.  Set another, valid, filter, or leave it alone.
  452. DIAGNOSTICS
  453.     None.
  454. SEE ALSO
  455.     CxObjError()
  456. NAME    CxMsgID()
  457.     LONG    id = CxMsgID(cxm);
  458.     CxMsg    *cxm;
  459. DESCRIPTION
  460.     Returns the value associated with the cause or source of the
  461.     Commodities message 'cxm.'  Values are provided by the application
  462.     when a Sender or Custom object is created.
  463. DIAGNOSTICS
  464.     If not specified by the application, the ID value of a Commodities
  465.     message will be null.  It is suggested that using non-null
  466.     values in your program as a rule may identify some possible errors.
  467. SEE ALSO
  468.     CxSender()
  469.     CxCustom()
  470. NAME    AttachCxObj()
  471.     void    AttachCxObj(headobj, co);
  472.     CxObj    *headobj;
  473.     CxObj    *co;
  474. DESCRIPTION
  475.     Appends object 'co' to the list of object 'headobj,' using the
  476.     Exec function AddTail().  Returns 'headobj.'
  477. DIAGNOSTICS
  478.     If 'co' is null, this function will record that fact in the
  479.     internal accumulated error of 'headobj.'  This error record
  480.     can be retrieved using CxObjError() and cleared using
  481.     ClearCxObjError().
  482. SEE ALSO
  483.     exec.library/AddTail()
  484.     Objects and Messages (in Reference Manual)
  485.     CxObjError(), ClearCxObjError()
  486. NAME    EnqueueCxObj()
  487.     void    EnqueueCxObj(headobj, co);
  488.     CxObj    *headobj;
  489.     CxObj    *co;
  490. DESCRIPTION
  491.     Puts object 'co' into the list of object 'headobj,' using the
  492.     Exec function Enqueue().  Returns 'headobj.'
  493.     This function uses the priority of the Commodities object as a node.
  494.     This priority can be set using SetCxObjPri().
  495. DIAGNOSTICS
  496.     If 'co' is null, will record that fact in the internal accumulated
  497.     error of 'headobj.'  This error record can be retrieved using
  498.     CxObjError() and cleared using ClearCxObjError().
  499. SEE ALSO
  500.     exec.library/Enqueue()
  501.     SetCxObjPri()
  502.     Objects and Messages (in Reference Manual)
  503.     CxObjError(), ClearCxObjError()
  504. NAME    InsertCxObj()
  505.     void    InsertCxObj(headobj, co, pred);
  506.     CxObj    *headobj;
  507.     CxObj    *co;
  508.     CxObj    *pred;
  509. DESCRIPTION
  510.     Adds object 'co' to the list of object 'headobj,' using the
  511.     Exec function Insert().  Returns 'headobj.'
  512.     As described in the autodocs for exec.library/Insert(), 'co' will
  513.     be inserted in the list of 'headobj' prior to 'pred.'  Even though
  514.     Insert() doesn't use the list header unless 'pred' is null, calling
  515.     InsertCxObj() you should always pass a valid 'headobj' and a possibly
  516.     null 'pred.'
  517. DIAGNOSTICS
  518.     If 'co' is null, this will be recorded in the internal accumulated
  519.     error of 'headobj.'  This error record can be retrieved using
  520.     CxObjError() and cleared using ClearCxObjError().
  521. SEE ALSO
  522.     exec.library/Insert()
  523.     Objects and Messages (in Reference Manual)
  524.     CxObjError(), ClearCxObjError()
  525. NAME    RemoveCxObj()
  526.     void    RemoveCxObj(co);
  527.     CxObj    *co;
  528. DESCRIPTION
  529.     Removes Commodities object 'co' from any list he is be a part of.
  530.     Will not crash if 'co' is null, or if it has not been inserted
  531.     in a list (and is not corrupted).
  532.     It is not recommended to remove a broker from the master list.
  533. DIAGNOSTICS
  534.     None.
  535. SEE ALSO
  536.     Objects and Messages (in Reference Manual)
  537. NAME    SetCxObjPri()
  538.     void    SetCxObjPri(co, pri)
  539.     CxObj    *co;
  540.     LONG    pri;
  541. DESCRIPTION
  542.     This function sets the priority of a Commodities object for the
  543.     purposes of EnqueueCxObj().  Note that the Commodities list
  544.     mechanisms are based on Amiga Exec lists, so the priority is
  545.     recorded as a signed byte.  Please keep values in range.  A
  546.     value of zero is usually fine.
  547.     It is strongly recommended that the ToolTypes environment be
  548.     utilized to provide end-user control over the priority of
  549.     brokers, but application specific ordering of other objects
  550.     within their lists is not dictated.
  551. DIAGNOSTICS
  552.     None.
  553. SEE ALSO
  554.     ToolTypes and the Commodities Environment (in Reference Manual)
  555.     EnqueueCxObj()
  556. NAME    FindBroker()
  557.     CxObj    *broker = FindBroker(name);
  558.     char    *name;
  559. DESCRIPTION
  560.     Looks for a Commodities broker whose node name is 'name' in the
  561.     Commodities Object List.
  562.     All uses of this function by applications are highly suspect.
  563. DIAGNOSTICS
  564.     Returns NULL if 'name' not found.
  565. SEE ALSO
  566.     Objects and Messages (in Reference Manual)
  567. NAME    CxMsgType()
  568.     ULONG    type = CxMsgType(cxm);
  569.     CxMsg    *cxm;
  570. DESCRIPTION
  571.     Returns the type of a Commodities message.  Possible values of
  572.     'type' are found in "cxusr.h."  Most Commodities messages 
  573.     are Input Event messages.
  574. DIAGNOSTICS
  575.     The value NULL should never be returned, if 'cxm' points to
  576.     a valid message.
  577. SEE ALSO
  578. NAME    CxMsgData()
  579.     char    *contents = CxMsgData(cxm);
  580.     CxMsg    *cxm;
  581. DESCRIPTION
  582.     Most Commodities messages contain meaningful data, such as an
  583.     InputEvent structure.  A pointer to this data may be obtained by
  584.     using this function.  A valid, non-null pointer will always
  585.     be returned if 'cxm' is valid.
  586.     You may get a Commodities message from a synchronous (custom
  587.     object) or asynchronous (sender object) source.  In the second
  588.     case, 'contents' is not valid after you have replied to the message.
  589. DIAGNOSTICS
  590.     If 'cxm' is null, returns NULL.
  591. SEE ALSO
  592.     CxSender()
  593.     CxCustom()
  594. NAME    DisposeCxMsg()
  595.     void    DisposeCxMsg(cxm);
  596.     CxMsg    *cxm;
  597. DESCRIPTION
  598.     Eliminates the Commodities message pointed to by 'cxm.'
  599.     Can be used to 'swallow' InputEvents by disposing of
  600.     every Commodities message of type CXM_IEVENT.
  601. DIAGNOSTICS
  602.     None.
  603. SEE ALSO
  604. NAME    RouteCxMsg()
  605.     void    RouteCxMsg(cxm, co);
  606.     CxMsg    *cxm;
  607.     CxObj    *co;
  608. DESCRIPTION
  609.     Establishes the next destination of a Commodities message
  610.     to be 'co,' which must be a valid Commodities object, and
  611.     must be linked in ultimately to the Commodities Object List.
  612.     Such a routing of an object is analogous to a 'goto' in a 
  613.     program.  There is no effect on the message's routing stack.
  614. DIAGNOSTICS
  615.     None.
  616. SEE ALSO
  617.     DivertCxMsg()
  618. NAME    DivertCxMsg()
  619.     void    DivertCxMsg(cxm, headobj, returnobj);
  620.     CxMsg    *cxm;
  621.     CxObj    *headobj;
  622.     CxObj    *returnobj;
  623. DESCRIPTION
  624.     Sends Commodities message 'cxm' down the list of objects attached to
  625.     'headobj.'  The pointer 'returnobj' is first pushed onto the
  626.     routing stack of 'cxm' so that when the end of the list of 'headobj'
  627.     is reached the SUCCESSOR of 'returnobj' is the next destination.
  628.     For example, when a filter finds a match with a message, the
  629.     message is diverted down the filter's list like this:
  630.         DivertCxMsg(cxm, filter, filter);.
  631. DIAGNOSTICS
  632.     None.
  633. SEE ALSO
  634.     Reference Manual
  635. NAME    HotKey()  --    SCANNED LIBRARY
  636.     CxObj    *filter = Hotkey(descr, port, ID);
  637.     char            *descr;
  638.     struct MsgPort    *port;
  639.     LONG            ID;
  640. DESCRIPTION
  641.     This function is not part of "commodities.library," but
  642.     is in the scanned library cx_support.lib.  It creates
  643.     a triad of Commodities objects to accomplish a high-level
  644.     function.
  645.     The three objects are a filter, which is created to match
  646.     by the call CxFilter(descr), a sender created by the call
  647.     CxSender(port, ID), and a translator which is created by
  648.     CxTranslate(NULL), so that it swallows any Commodities
  649.     input event messages that are passed down by the filter.
  650.     This is the simple way to get a message sent to your program
  651.     when the user performs a particular input action.
  652.     It is strongly recommended that the ToolTypes environment
  653.     be used to allow the user to specify the input descriptions
  654.     for your application's hotkeys.
  655. DIAGNOSTICS
  656.     Returns NULL and cleans up after itself if any problems occur
  657.     creating the objects.  It may be wise to test filter using
  658.     CxObjError() to insure that 'descr' was a valid description.
  659. SEE ALSO
  660.     ToolTypes and the Commodities Environment (in Reference Manual)
  661.     CxFilter(), CxSender(), CxTranslate(), CxObjError()
  662. NAME    ArgArray    --    SCANNED LIBRARY
  663.     char    **ttypes = ArgArrayInit(argc, argv);
  664.     int        argc;
  665.     char    **argv;
  666. DESCRIPTION
  667.     This function is not part of "commodities.library," but is
  668.     in "cx_support.lib."
  669.     ArgArrayInit() returns a null-terminated array
  670.     of strings suitable for sending to the icon.library function
  671.     FindToolType().  This array will be the ToolTypes array of the
  672.     program's icon, if it was started from the workbench.  It will
  673.     be just 'argv' if the program was started from the CLI.
  674.     NOTE WELL: Your C compiler must null terminate '*argv[]' for this
  675.     scheme to work.  Aztec does, in the version Commodities was
  676.     developed with.
  677.     Pass ArgArrayInit() your startup arguments passed to main().
  678.     ArgArrayInit() opens the icon.library (even if the caller was
  679.     started from a CLI, so that the function FindToolType() can 
  680.     be used) and may call GetDiskObject(), so clean up is necessary
  681.     when the strings are no longer needed.  The function ArgArrayDone()
  682.     does just that.
  683.     Use of these routines facilitates the use of ToolTypes or command
  684.     line arguments to control end-user parameters in Commodities 
  685.     applications.  For example, a filter used to trap a keystroke for
  686.     popping up a window might be created by something like this:
  687.     char    *ttypes = ArgArrayInit(argc, argv);
  688.     CxObj    *filter    = UserFilter(ttypes, "POPWINDOW", "alt f1");
  689.     ... with ...
  690.     CxObj    *
  691.     UserFilter(tt, action_name, default_descr)
  692.     char    **tt;            /* null-terminated (char *(*)[])    */
  693.     char    *action_name;    /* name of your semantic action        */
  694.     char    *default_descr;    /* used if user doesn't provide        */
  695.         char    *desc;
  696.         desc = FindToolType(tt, action_name);
  697.         return ( CxFilter(desc? desc: default_descr) );
  698.     In this way the user can assign "alt f2" to the action by
  699.     entering a tooltype in the programs icon of the form:
  700.         POPWINDOW=alt f2
  701.     or by starting the program from the CLI with like so:
  702.         myprogram "POPWINDOW=alt f2"
  703. DIAGNOSTICS
  704.     ArgArrayInit() would return NULL if any problems occured.
  705. SEE ALSO
  706.     ArgArrayDone()
  707.     ArgString()
  708.     ArgInt()
  709.     icon.library/FindToolType()
  710.     cx_support.lib probably will have UserFilter().
  711. NAME    ArgArrayDone()        ---    SCANNED LIBRARY
  712.     void    ArgArrayDone();
  713. DESCRIPTION
  714.     This function closes the disk object and Icon Library opened
  715.     by ArgArrayInit().  Don't call this until you are done using
  716.     the ToolTypes argument strings.
  717. DIAGNOSTICS
  718.     None.
  719. SEE ALSO
  720.     ArgArrayInit()
  721. NAME    ArgString()        ---    SCANNED LIBRARY
  722.     char    *string = ArgString(tt, string, defaultstring)
  723.     char    **tt;
  724.     char    *t;
  725.     char    *defaultstring;
  726. DESCRIPTION
  727.     This function looks in the ToolTypes array 'tt' returned
  728.     by ArgArrayInit() for the entry for 'string' and returns
  729.     the "value" for 'string.'  The entry and value have the
  730.     standard ToolTypes format such as:
  731.         ENTRY=Value
  732.     If an entry for 'string' is not found, the defaultstring
  733.     will be returned.
  734. DIAGNOSTICS
  735.     None.
  736. SEE ALSO
  737.     ArgArrayInit()
  738. NAME    ArgInt()        ---    SCANNED LIBRARY
  739.     int    value = ArgInt(tt, string, defaultval)
  740.     char    **tt;
  741.     char    *t;
  742.     int        defaultval;
  743. DESCRIPTION
  744.     This function looks in the ToolTypes array 'tt' returned
  745.     by ArgArrayInit() for the entry for 'string' and returns
  746.     the "value" for 'string.'  The entry and value have the
  747.     standard ToolTypes format such as:
  748.         ENTRY=Value
  749.     In the case of this function, value will be passed through
  750.     'atoi()' before returning.
  751.     If an entry for 'string' is not found, the integer 'defaultval'
  752.     will be returned.
  753. DIAGNOSTICS
  754.     None.
  755. SEE ALSO
  756.     ArgArrayInit()
  757. NAME    InvertKeyMap()
  758.     ULONG    retval = InvertKeyMap(ansicode, ie, km)
  759.     ULONG                ansicode;
  760.     struct InputEvent    *ie;
  761.     struct KeyMap        *km;
  762. DESCRIPTION
  763.     Figures out what InputEvent translates to an ANSI character code
  764.     'ansicode.'  The InputEvent pointed to by 'ie' is filled in
  765.     with that information.  The KeyMap 'km' is used, unless it
  766.     is NULL, in which case the system standard keymap (as defined
  767.     when commodities.library is initialized) is used.
  768.     This function currently handles one-deep dead keys (such as
  769.     <alt f>o).  It does not look up the high key map (keystrokes
  770.     with scan codes greater than 0x40), and misses system changes to
  771.     the default key map.
  772. DIAGNOSTICS
  773.     Returns non-negative value if it worked, less than zero, with
  774.     error values to be defined in the future.
  775. SEE ALSO
  776.     InvertString()
  777. NAME    InvertString()    --    SCANNED LIBRARY
  778.     struct InputEvent    *InvertString(str, km)
  779.     char            *str;
  780.     struct KeyMap    *km;
  781. DESCRIPTION
  782.     This function returns a linked list of input events which would
  783.     translate into the string using the keymap 'km' (of the system
  784.     default keymap if 'km' is NULL).
  785.     The null-terminated 'str' may contain:
  786.     -ANSI character codes
  787.     -backslash escaped characters: 
  788.         \n    -    return
  789.         \r    -    return
  790.         \t    -    tab
  791.         \0    -    don't use this, ok?
  792.         \\    -    backslash
  793.     -a text description of an input event as used by ParseIX(),
  794.      enclosed in angle brackets.
  795.     An example is:
  796.         abc<alt f1>\nhi there.
  797.     NOTE: you are responsible for freeing the InputEvents that this
  798.     function allocates.  You may use FreeIEvents().
  799. DIAGNOSTICS
  800.     Returns NULL if there is a problem, most often an illegal description
  801.     enclosed in angles.
  802. SEE ALSO
  803.     ParseIX()
  804.     FreeIEvents()
  805. NAME    AddIEvents()
  806.     void    AddIEvents(ie)
  807.     struct InputEvent    *ie;
  808. DESCRIPTION
  809.     This function adds a null-terminated linked list to the input
  810.     stream of Commodities.  It is a touch easier than using the
  811.     input device directly.
  812.     The contents of the input events are copied into Commodities internal
  813.     messages, so they may be disposed of as soon as this call returns.
  814.     The messages are initially routed to the first Broker in the
  815.     Commodities Object List.
  816. DIAGNOSTICS
  817.     None.
  818. SEE ALSO
  819.     FreeIEvents()
  820.